IRIX Base Documentation 2001 May

home *** CD-ROM | disk | FTP | other *** search

/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat3c / getsubopt.z / getsubopt

Wrap

Text File | 1998-10-20 | 17.0 KB | 198 lines

ggggeeeettttssssuuuubbbboooopppptttt((((3333CCCC)))) ggggeeeettttssssuuuubbbboooopppptttt((((3333CCCC)))) NNNNAAAAMMMMEEEE _gggg_eeee_tttt_ssss_uuuu_bbbb_oooo_pppp_tttt - parse suboptions from a string SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_tttt_dddd_llll_iiii_bbbb_...._hhhh_>>>> _iiii_nnnn_tttt _gggg_eeee_tttt_ssss_uuuu_bbbb_oooo_pppp_tttt _((((_cccc_hhhh_aaaa_rrrr _****_****_oooo_pppp_tttt_iiii_oooo_nnnn_pppp_,,,, _cccc_hhhh_aaaa_rrrr _****_cccc_oooo_nnnn_ssss_tttt _****_tttt_oooo_kkkk_eeee_nnnn_ssss_,,,, _cccc_hhhh_aaaa_rrrr _****_****_vvvv_aaaa_llll_uuuu_eeee_pppp_))))_;;;; DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN _gggg_eeee_tttt_ssss_uuuu_bbbb_oooo_pppp_tttt parses suboptions in a flag argument that was initially parsed by _gggg_eeee_tttt_oooo_pppp_tttt(3C). These suboptions are separated by commas and may consist of either a single token or a token-value pair separated by an equal sign. Since commas delimit suboptions in the option string, they are not allowed to be part of the suboption or the value of a suboption. A command that uses this syntax is _mmmm_oooo_uuuu_nnnn_tttt(1M), which allows the user to specify mount parameters with the _----_oooo option as follows: _mmmm_oooo_uuuu_nnnn_tttt _----_oooo _rrrr_wwww_,,,,_hhhh_aaaa_rrrr_dddd_,,,,_bbbb_gggg_,,,,_wwww_ssss_iiii_zzzz_eeee_====_1111_0000_2222_4444 _ssss_pppp_eeee_eeee_dddd_::::_////_uuuu_ssss_rrrr _////_uuuu_ssss_rrrr In this example there are four suboptions: _rrrr_wwww, _hhhh_aaaa_rrrr_dddd, _bbbb_gggg, and _wwww_ssss_iiii_zzzz_eeee, the last of which has an associated value of 1024. _gggg_eeee_tttt_ssss_uuuu_bbbb_oooo_pppp_tttt takes the address of a pointer to the option string, a vector of possible tokens, and the address of a value string pointer. It returns the index of the token that matched the suboption in the input string or -1 if there was no match. If the option string at _o_p_t_i_o_n_p contains only one suboption, _gggg_eeee_tttt_ssss_uuuu_bbbb_oooo_pppp_tttt updates _o_p_t_i_o_n_p to point to the null character at the end of the string; otherwise it isolates the suboption by replacing the comma separator with a null character, and updates _o_p_t_i_o_n_p to point to the start of the next suboption. If the suboption has an associated value, _gggg_eeee_tttt_ssss_uuuu_bbbb_oooo_pppp_tttt updates _v_a_l_u_e_p to point to the value's first character. Otherwise it sets _v_a_l_u_e_p to _NNNN_UUUU_LLLL_LLLL. The token vector is organized as a series of pointers to null strings. The end of the token vector is identified by a null pointer. When _gggg_eeee_tttt_ssss_uuuu_bbbb_oooo_pppp_tttt returns, if _v_a_l_u_e_p is not _NNNN_UUUU_LLLL_LLLL, then the suboption processed included a value. The calling program may use this information to determine if the presence or lack of a value for this suboption is an error. Additionally, when _gggg_eeee_tttt_ssss_uuuu_bbbb_oooo_pppp_tttt fails to match the suboption with the tokens in the _t_o_k_e_n_s array, the calling program should decide if this is an error, or if the unrecognized option should be passed to another program. EEEEXXXXAAAAMMMMPPPPLLLLEEEE The following code fragment shows how to process options to the _mmmm_oooo_uuuu_nnnn_tttt command using _gggg_eeee_tttt_ssss_uuuu_bbbb_oooo_pppp_tttt. _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_tttt_dddd_llll_iiii_bbbb_...._hhhh_>>>> _cccc_hhhh_aaaa_rrrr _****_mmmm_yyyy_oooo_pppp_tttt_ssss_[[[[_]]]] _==== _{{{{ _####_dddd_eeee_ffff_iiii_nnnn_eeee _RRRR_EEEE_AAAA_DDDD_OOOO_NNNN_LLLL_YYYY _0000 PPPPaaaaggggeeee 1111 ggggeeeettttssssuuuubbbboooopppptttt((((3333CCCC)))) ggggeeeettttssssuuuubbbboooopppptttt((((3333CCCC)))) _""""_rrrr_oooo_""""_,,,, _####_dddd_eeee_ffff_iiii_nnnn_eeee _RRRR_EEEE_AAAA_DDDD_WWWW_RRRR_IIII_TTTT_EEEE _1111 _""""_rrrr_wwww_""""_,,,, _####_dddd_eeee_ffff_iiii_nnnn_eeee _WWWW_RRRR_IIII_TTTT_EEEE_SSSS_IIII_ZZZZ_EEEE _2222 _""""_wwww_ssss_iiii_zzzz_eeee_""""_,,,, _####_dddd_eeee_ffff_iiii_nnnn_eeee _RRRR_EEEE_AAAA_DDDD_SSSS_IIII_ZZZZ_EEEE _3333 _""""_rrrr_ssss_iiii_zzzz_eeee_""""_,,,, _NNNN_UUUU_LLLL_LLLL_}}}}_;;;; _mmmm_aaaa_iiii_nnnn_((((_aaaa_rrrr_gggg_cccc_,,,, _aaaa_rrrr_gggg_vvvv_)))) _iiii_nnnn_tttt _aaaa_rrrr_gggg_cccc_;;;; _cccc_hhhh_aaaa_rrrr _****_****_aaaa_rrrr_gggg_vvvv_;;;; _{{{{ _iiii_nnnn_tttt _ssss_cccc_,,,, _cccc_,,,, _eeee_rrrr_rrrr_ffff_llll_aaaa_gggg_;;;; _cccc_hhhh_aaaa_rrrr _****_oooo_pppp_tttt_iiii_oooo_nnnn_ssss_,,,, _****_vvvv_aaaa_llll_uuuu_eeee_;;;; _eeee_xxxx_tttt_eeee_rrrr_nnnn _cccc_hhhh_aaaa_rrrr _****_oooo_pppp_tttt_aaaa_rrrr_gggg_;;;; _eeee_xxxx_tttt_eeee_rrrr_nnnn _iiii_nnnn_tttt _oooo_pppp_tttt_iiii_nnnn_dddd_;;;; _.... _.... _.... _wwww_hhhh_iiii_llll_eeee_((((_((((_cccc _==== _gggg_eeee_tttt_oooo_pppp_tttt_((((_aaaa_rrrr_gggg_cccc_,,,, _aaaa_rrrr_gggg_vvvv_,,,, _""""_aaaa_bbbb_ffff_::::_oooo_::::_""""_))))_)))) _!!!!_==== _----_1111_)))) _{{{{ _ssss_wwww_iiii_tttt_cccc_hhhh _((((_cccc_)))) _{{{{ _cccc_aaaa_ssss_eeee _''''_aaaa_''''_:::: _////_**** _pppp_rrrr_oooo_cccc_eeee_ssss_ssss _aaaa _oooo_pppp_tttt_iiii_oooo_nnnn _****_//// _bbbb_rrrr_eeee_aaaa_kkkk_;;;; _cccc_aaaa_ssss_eeee _''''_bbbb_''''_:::: _////_**** _pppp_rrrr_oooo_cccc_eeee_ssss_ssss _bbbb _oooo_pppp_tttt_iiii_oooo_nnnn _****_//// _bbbb_rrrr_eeee_aaaa_kkkk_;;;; _cccc_aaaa_ssss_eeee _''''_ffff_''''_:::: _oooo_ffff_iiii_llll_eeee _==== _oooo_pppp_tttt_aaaa_rrrr_gggg_;;;; _bbbb_rrrr_eeee_aaaa_kkkk_;;;; _cccc_aaaa_ssss_eeee _''''_????_''''_:::: _eeee_rrrr_rrrr_ffff_llll_aaaa_gggg_++++_++++_;;;; _bbbb_rrrr_eeee_aaaa_kkkk_;;;; _cccc_aaaa_ssss_eeee _''''_oooo_''''_:::: _oooo_pppp_tttt_iiii_oooo_nnnn_ssss _==== _oooo_pppp_tttt_aaaa_rrrr_gggg_;;;; _wwww_hhhh_iiii_llll_eeee _((((_****_oooo_pppp_tttt_iiii_oooo_nnnn_ssss _!!!!_==== _''''_\\\\_0000_''''_)))) _{{{{ _ssss_wwww_iiii_tttt_cccc_hhhh_((((_gggg_eeee_tttt_ssss_uuuu_bbbb_oooo_pppp_tttt_((((_&&&&_oooo_pppp_tttt_iiii_oooo_nnnn_ssss_,,,,_mmmm_yyyy_oooo_pppp_tttt_ssss_,,,,_&&&&_vvvv_aaaa_llll_uuuu_eeee_)))) _{{{{ _cccc_aaaa_ssss_eeee _RRRR_EEEE_AAAA_DDDD_OOOO_NNNN_LLLL_YYYY _:::: _////_**** _pppp_rrrr_oooo_cccc_eeee_ssss_ssss _rrrr_oooo _oooo_pppp_tttt_iiii_oooo_nnnn _****_//// _bbbb_rrrr_eeee_aaaa_kkkk_;;;; _cccc_aaaa_ssss_eeee _RRRR_EEEE_AAAA_DDDD_WWWW_RRRR_IIII_TTTT_EEEE _:::: _////_**** _pppp_rrrr_oooo_cccc_eeee_ssss_ssss _rrrr_wwww _oooo_pppp_tttt_iiii_oooo_nnnn _****_//// _bbbb_rrrr_eeee_aaaa_kkkk_;;;; _cccc_aaaa_ssss_eeee _WWWW_RRRR_IIII_TTTT_EEEE_SSSS_IIII_ZZZZ_EEEE _:::: _////_**** _pppp_rrrr_oooo_cccc_eeee_ssss_ssss _wwww_ssss_iiii_zzzz_eeee _oooo_pppp_tttt_iiii_oooo_nnnn _****_//// _iiii_ffff _((((_vvvv_aaaa_llll_uuuu_eeee _====_==== _NNNN_UUUU_LLLL_LLLL_)))) _{{{{ _eeee_rrrr_rrrr_oooo_rrrr______nnnn_oooo______aaaa_rrrr_gggg_((((_))))_;;;; _eeee_rrrr_rrrr_ffff_llll_aaaa_gggg_++++_++++_;;;; _}}}} _eeee_llll_ssss_eeee _wwww_rrrr_iiii_tttt_eeee______ssss_iiii_zzzz_eeee _==== _aaaa_tttt_oooo_iiii_((((_vvvv_aaaa_llll_uuuu_eeee_))))_;;;; _bbbb_rrrr_eeee_aaaa_kkkk_;;;; _cccc_aaaa_ssss_eeee _RRRR_EEEE_AAAA_DDDD_SSSS_IIII_ZZZZ_EEEE _:::: _////_**** _pppp_rrrr_oooo_cccc_eeee_ssss_ssss _rrrr_ssss_iiii_zzzz_eeee _oooo_pppp_tttt_iiii_oooo_nnnn _****_//// _iiii_ffff _((((_vvvv_aaaa_llll_uuuu_eeee _====_==== _NNNN_UUUU_LLLL_LLLL_)))) _{{{{ _eeee_rrrr_rrrr_oooo_rrrr______nnnn_oooo______aaaa_rrrr_gggg_((((_))))_;;;; _eeee_rrrr_rrrr_ffff_llll_aaaa_gggg_++++_++++_;;;; _}}}} _eeee_llll_ssss_eeee PPPPaaaaggggeeee 2222 ggggeeeettttssssuuuubbbboooopppptttt((((3333CCCC)))) ggggeeeettttssssuuuubbbboooopppptttt((((3333CCCC)))) _rrrr_eeee_aaaa_dddd______ssss_iiii_zzzz_eeee _==== _aaaa_tttt_oooo_iiii_((((_vvvv_aaaa_llll_uuuu_eeee_))))_;;;; _bbbb_rrrr_eeee_aaaa_kkkk_;;;; _dddd_eeee_ffff_aaaa_uuuu_llll_tttt _:::: _////_**** _pppp_rrrr_oooo_cccc_eeee_ssss_ssss _uuuu_nnnn_kkkk_nnnn_oooo_wwww_nnnn _tttt_oooo_kkkk_eeee_nnnn _****_//// _eeee_rrrr_rrrr_oooo_rrrr______bbbb_aaaa_dddd______tttt_oooo_kkkk_eeee_nnnn_((((_vvvv_aaaa_llll_uuuu_eeee_))))_;;;; _eeee_rrrr_rrrr_ffff_llll_aaaa_gggg_++++_++++_;;;; _bbbb_rrrr_eeee_aaaa_kkkk_;;;; _}}}} _}}}} _bbbb_rrrr_eeee_aaaa_kkkk_;;;; _}}}} _}}}} _iiii_ffff _((((_eeee_rrrr_rrrr_ffff_llll_aaaa_gggg_)))) _{{{{ _////_**** _pppp_rrrr_iiii_nnnn_tttt _uuuu_ssss_aaaa_gggg_eeee _iiii_nnnn_ssss_tttt_rrrr_uuuu_cccc_tttt_iiii_oooo_nnnn_ssss _eeee_tttt_cccc_.... _****_//// _}}}} _ffff_oooo_rrrr _((((_;;;; _oooo_pppp_tttt_iiii_nnnn_dddd_<<<<_aaaa_rrrr_gggg_cccc_;;;; _oooo_pppp_tttt_iiii_nnnn_dddd_++++_++++_)))) _{{{{ _////_**** _pppp_rrrr_oooo_cccc_eeee_ssss_ssss _rrrr_eeee_mmmm_aaaa_iiii_nnnn_iiii_nnnn_gggg _aaaa_rrrr_gggg_uuuu_mmmm_eeee_nnnn_tttt_ssss _****_//// _}}}} _.... _.... _.... _}}}} SSSSEEEEEEEE AAAALLLLSSSSOOOO getopt(3C) DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS _gggg_eeee_tttt_ssss_uuuu_bbbb_oooo_pppp_tttt returns -1 when the token it is scanning is not in the token vector. The variable addressed by _v_a_l_u_e_p contains a pointer to the first character of the token that was not recognized rather than a pointer to a value for that token. The variable addressed by _o_p_t_i_o_n_p points to the next option to be parsed, or a null character if there are no more options. NNNNOOOOTTTTEEEESSSS During parsing, commas in the option input string are changed to null characters. White space in tokens or token-value pairs must be protected from the shell by quotes. PPPPaaaaggggeeee 3333